home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 003 / litebar.arc / LITEBAR.DOC < prev    next >
Encoding:
Text File  |  1987-07-25  |  17.9 KB  |  444 lines
  1. Documentation for LITEBAR v. 4.2
  2. 7/25/87
  3.  
  4. Copyright (c) 1987 R. Russell Freeland, Synergy Corp.
  5.  
  6.  
  7. ________________________________________________________________________________
  8.                          -- Overview --
  9. ________________________________________________________________________________
  10.  
  11. LITEBAR is a BIN routine that can be used to generate quick menus
  12. from dBASE III Plus.  Some of its features are:
  13.  
  14. o Very little overhead in terms of memory required
  15.  
  16. o Parameters taken from either memory variables or a text file
  17.  
  18. o Menus can be horizontal or vertical (or zigzag for that
  19.   matter)
  20.  
  21. o Compatibility with Clipper, Quicksilver, FoxBASE+, and dBASE 
  22.   III Plus
  23.  
  24. o Up to 50 menu options can be displayed at once
  25.  
  26. o Colors are selectable (monochrome monitors will be sensed and
  27.   color parameters will be overridden)
  28.  
  29. o Function keys can be trapped (optionally)
  30.  
  31. o Keys which are normally reserved for LITEBAR can be trapped and
  32.   returned to the calling program
  33.  
  34. o Help prompts can be displayed anywhere on the screen
  35.  
  36. o The time can be displayed while LITEBAR is waiting for input
  37.  
  38. o LITEBAR can "remember" the last option that was pressed and
  39.   highlight that option first the next time you call it
  40.  
  41. o Support for 43-line EGA mode
  42.  
  43. o turn on/off snow suppression (default is on for CGA)
  44.  
  45. o selectable "first option"
  46.  
  47. o Banners (only partially implemented w/this version)
  48.  
  49.  
  50. Options that are likely to be added to LITEBAR:
  51. ______________________________________________
  52.  
  53. o Zoom windows
  54. o Borders around windows
  55. o Enhanced trigger key trapping options
  56. o Enhanced error reporting
  57. o Script files--this is a high priority, should make possible more efficient
  58.   "pulldown" style menus
  59.  
  60. If you use this program, I would appreciate a contribution.  It started as a
  61. tiny experiment but *many* hours have gone into its development at this point.
  62. I suggest a $40 registration fee.  If you register, I will make the source
  63. code available to you on the Synergy BBS.  You will also have access to the
  64. full documentation, which reveals some of the "other" options detailed at the
  65. end of this text.  Updates will be free if you download them from the BBS.
  66. No "runtime" charges are necessary; pay your $40 and go.  This seems reasonable
  67. to me, especially when I look at the competition.
  68.  
  69. Also, I will make available to registered users a smaller version without the 
  70. screen save buffers, which will reduce by at leat 8K the BIN/OBJ files' size.
  71.  
  72. ***************** If you use this program commercially, registration is
  73. ***************** mandatory!!!
  74.  
  75. If you send $75 instead, you will be licensed for all Synergy utilities.
  76. Synergy BINs are FOXBASE-, QS- and mostly Clipper-compatible and include:
  77.  
  78. SCROLL   screen window scrolling (left right down up), coloring, fading, bolding
  79. SAVER    screen save/restore, write to disk, read from disk, etc.
  80. DISKSPAC free space any disk--returns error for drive not ready
  81. CD       get current drive/directory
  82. ENCRYPT  encrypt/decrypt strings
  83. SRCHPATH search DOS path for file
  84. FINDFL   find all files matching a wildcard, return all directory info
  85. NETINFO  get net name (more to come)
  86. MEMCHECK check memory on the system, also how much when dBASE was loaded
  87. DIREXIST check existence of drive/directory
  88. FSIZE    get size of file(s)
  89. CHATTR   change attributes of (files)
  90. SAT      SuperAt(), find every occurrence of a substring in one CALL
  91. HANDLES  Get *true* amount of available file handles
  92. RAND     Random number generator
  93. IN/OUT   Port access
  94. LBMRD    Litebars using UI's MRD.
  95. SOUNDEX  get SOUNDEX codes
  96. DELAY    delay specified number (and fraction) of seconds
  97. VALDRIVE find out all valid drives on system
  98. EQUIP    find out what equipment you're running on
  99. GETCOLOR find out what the color is on the screen now (at cursor position)
  100. SINE/COSINE/TANGENT etc.
  101.  
  102. ...and many more.  Also startup code for C compilers to write your own BINs
  103. in C is coming soon (in Beta now).  Sign up now, the price is going up as soon 
  104. as I crank out some more <grin>.
  105.  
  106. Synergy also will make available a parameter-generating program to make creation
  107. of LITEBAR menus easier.  A rudimentary version written in dBASE is available
  108. now.  This program (LBGEN.PRG) is will be an example of how to use LITEBAR as
  109. soon as I comment it <grin>.  In the meantime, it is available to make 
  110. generation (and modification) of menus easier.  It only generates text files
  111. for input to LITEBAR at this time.  In the ARC with this file there should be
  112. an LBGEN.ARC that has a demo version of LBGEN and some rudimentary documentation
  113. for it.  The demo version is limited to three menu choices, and is encrypted
  114. using DBC.
  115. ________________________________________________________________________________
  116.  
  117. dBASE III Plus(tm) is a trademark of Ashton-Tate
  118. Quicksilver(tm) is a trademark of Wordtech
  119. Clipper(tm) is a trademark of Nantucket
  120. FoxBASE+(tm) is a trademark of Fox Software
  121. WordStar(tm) is a trademark of Micropro International
  122.  
  123. These are all (relative to me) huge corporations who could sue the living
  124. beejeezus outta me, so I thought I'd just mention that stuff.
  125.  
  126.  
  127. ________________________________________________________________________________
  128.  
  129. Disclaimer:
  130.  
  131. This program has been tested rather thoroughly by many people.  It is "lean
  132. and mean" which means it will run totally amok, crashing and burning, if you
  133. misplace a comma in a parameter.  This is my method of getting you to register,
  134. so you can get the generation program <grin>.  If it doesn't look "lean"
  135. in size, that's because there is 8K in screen buffer built in and 6K of Litebar
  136. parameter buffer.  LITEBAR will not trash your FAT, format your
  137. disk, corrupt memory, or any other really bad things.  But....if you manage to
  138. do any of those things I will:
  139.  
  140. 1) Swear that LITEBAR is not responsible.
  141. 2) Claim no responsibility in any case.
  142. 3) Not refund your money (if you sent any).
  143. ________________________________________________________________________________
  144.  
  145. Well, now that all that's oughtta the way, here's the documentation:
  146. ================================================================================
  147.  
  148. ________________________________________________________________________________
  149.                        -- General Usage --
  150. ________________________________________________________________________________
  151.  
  152.  
  153. LITEBAR is presently offered in two forms: as a BIN file for use
  154. from dBASE, FoxBASE+, and Quicksilver, and as an OBJ file to be
  155. linked to Clipper- or QS- compiled applications.
  156.  
  157. From any environment but Clipper, the syntax is:
  158.  
  159. LOAD LITEBAR
  160. CALL LITEBAR WITH <parameters>
  161.  
  162. In Clipper, the same syntax is used except that the file need not
  163. be LOADed, since it is already linked into the compiled EXE
  164. file.  If you wish to use the OBJ code for QS instead of the BIN file,
  165. use CCALL instead of CALL.
  166.  
  167. The procedure for linking LITEBAR to your compiled
  168. application is:
  169.  
  170. o First compile the application into OBJ code. 
  171. o At the LINK step, add LITEBAR to your list of OBJ modules for
  172.   LINK (or PLINK86)
  173.  
  174.  
  175.  
  176. ________________________________________________________________________________
  177.                        -- Parameter Options --
  178. ________________________________________________________________________________
  179.  
  180.  
  181. There are many types of of parameters that can be passed to LITEBAR.  The basic
  182. parameter list is preceded by optional "switches".  The switches must be 
  183. separated from the actual parameters by  the character "/" (not optional).  All
  184. switches and parameters are concatenated into one character variable to be 
  185. passed to LITEBAR.
  186.  
  187. The first parameter after the separating "/" character must always consist of 
  188. two attributes for color.  The first attribute is the color of unhighlighted
  189. menu options, the second is that of highlighted menu options.  They are 
  190. separated by a commas, and followed by a comma.  The colors are specified as
  191. decimal screen attributes.  If you are a registered user you will receive a
  192. program that allows you to pick from a grid of screen colors, otherwise refer
  193. to the installation program for Sidekick, Superkey, QEDIT, etc.
  194.  
  195. Each menu option is added to the passed parameter in the following format:
  196.  
  197. Option row,option column,option text,"\",option trigger key
  198.  
  199. For instance, to display a menu option at row 10, column 24 with text 
  200. "this is a test", the parameter string could include the variable moption_1
  201. where moption_1 is defined as:
  202.  
  203. moption_1="10,24, T)his is parameter one \T"
  204.  
  205. The trigger key for this option is "T".  Lower case T will be converted by
  206. Litebar to a capital.
  207.  
  208.  
  209.  
  210. Let's do a simple Lotus-style menu at the bottom of the screen:
  211.  
  212. low_high='112,111,'   && should work on mono monitor w/no override
  213. mchoice1="24,0, T)his is a demo \T"
  214. mchoice2="24,30, O)f litebar version \O"
  215. mchoice3="24,70, 4).0 \4"
  216.  
  217. mchoice="/"+low_high+mchoice1+mchoice2+mchoice3
  218. LOAD litebar
  219. CALL litebar WITH mchoice
  220.  
  221. Now to add help prompts, we'll change a few things.  First of all, we need to
  222. tell LITEBAR we're sending help parameters.  This is done with the "H" switch.
  223. We'll add a memvar called "switches", and then add the help prompts to each menu
  224. option:
  225.  
  226.  
  227. switches="H112,/"      && 112 is the attribute to use for erasing help
  228. low_high='112,111,'
  229. mchoice1="22,0, T)his is a demo \T\24,30, Help for option 1\"
  230. mchoice2="22,30, O)f litebar version \O\24,30, Help for option 2\"
  231. mchoice3="22,70, 4).0 \4\24,30, Help for option 4\"
  232.  
  233.  
  234. mchoice=switches+low_high+mchoice1+mchoice2+mchoice3
  235. CALL litebar WITH mchoice
  236.  
  237.  
  238. Continuations:
  239.  
  240. When you want to send a parameter to LITEBAR that exceeds 254 characters in
  241. length (dBASE doesn't allow strings > 254 bytes in length) you may break up the
  242. string into parts and append a semicolon to the end of each part (with the 
  243. exception of last part).
  244.  
  245. Example:
  246. m_param1 = "<whatever>"+";"
  247. m_param2 = "<whatever>"
  248.  
  249. CALL LITEBAR WITH m_param1
  250.  
  251. (LITEBAR will return into the first character of m_param1 a CHR(2)
  252. to indicate that it is waiting for more input.)
  253.  
  254. CALL LITEBAR WITH m_param2
  255.  
  256. It is easier in many cases to just put the parameter into a text file
  257. (see below).  The quickest way to use memvars for long menus is to 
  258. keep them in a memvar file, but to edit them is a pain unless you
  259. keep the code around that you used to create them.
  260.  
  261.  
  262.  
  263.  
  264. File input:
  265.  
  266. To tell LITEBAR to read its parameter from a file, just pass "F"+filename.
  267. There may be a little trouble if you don't have enough EOF marks at the end of 
  268. the file.  If you're having trouble with this option, try another text editor
  269. (EDLIN should do it, WordStar is ideal).  Subsequent versions will probably fix 
  270. this problem.
  271.  
  272. "Memory" option:
  273.  
  274. If you just pass a CHR(255), LITEBAR will "remember" the last passed param
  275. and key pressed, and resume with the last selected item highlighted.
  276.  
  277.  
  278. ________________________________________________________________________________
  279.                        -- "Switch" Options --
  280. ________________________________________________________________________________
  281.  
  282. There are many switches which can be sent to LITEBAR.  They should
  283. all precede the separator character "/" (in any order).  They are:
  284.  
  285. o Help char and attribute --"H" followed by an ASCII decimal string (attribute)
  286.   denotes that there will be help prompts.  The help text follows the
  287.   option trigger, separated by a \, starts with the row and column as with
  288.   option text, and ends with a backslash.  There must be separate help prompts 
  289.   for each option string.  The help attribute should match the background color 
  290.   of the screen as this is the color that the help will be "erased" with.
  291.   (You can use GETCOLOR.BIN to get this attribute if you're a registered user
  292.   of Synergy Utilities.)
  293.  
  294. o Function key trapping -- pass a "K" in the flags string--LITEBAR will trap
  295.   all function keys, returning CHR(4)+CHR(x) where x is the function key
  296.   pressed.
  297.  
  298. o Trap extra keys--you may pass "O"+scan code, scan code, etc.+"O"
  299.   to LITEBAR and it will trap those keys before it checks any other keys, 
  300.   returning a CHR(3)+CHR(trapped scan code) much in the same way as the 
  301.   function key option returns CHR(4)+CHR(number of function key)
  302.   Example: "O75,77O" says trap the left and right arrow keys and return
  303.   CHR(3)+CHR(75) if left arrow key is hit.  This enables you to trap
  304.   PgUp, PgDn, left and right arrows, etc. for special use.
  305.  
  306. o Time display -- "T0,6," gives time display at 0,6 in the same color as the
  307.   unhighlighted menu options.
  308.  
  309. o Force CR -- pass "E" (Enter) in the switches.
  310.  
  311. o Return whole string of option selected -- pass "V" (verbal).
  312.  
  313.  
  314. In most cases, LITEBAR returns the trigger key you pressed.  If my rudimentary
  315. error checking finds a problem, you get CHR(1) instead.  A continuation 
  316. character at the end of the passed parameter should get you a CHR(2).  If you
  317. specified the "V", "O", or "K" options you should get the return value described
  318. above.  See the demo programs for more details.
  319.  
  320.  
  321. ________________________________________________________________________________
  322.                         -- keys trapped by Litebar --
  323. ________________________________________________________________________________
  324.  
  325. Litebar will trap some keys internally for its own use, unless otherwise
  326. specified (with the "O" option).  They are left- and up-arrow (previous option),
  327. right- and down-arrow (next option), Home (first option), End (last option).
  328.  
  329. Keys which (should) always return from Litebar are: Enter (Return), whatever
  330. trigger key is specified (unless the "force CR" option is specified), and the
  331. Escape key (returns CHR(27)).  Other keys can be trapped with "K" or "O" as
  332. described above.
  333.  
  334. ________________________________________________________________________________
  335.                            -- "Other" Options --
  336. ________________________________________________________________________________
  337.  
  338. To consolidate a little, I built in most of the options from SCROLL3.BIN
  339. (available to registered Synergy Utility users) and SAVER02 (available to
  340. just about anyone with a modem).  I also threw in a few extras.
  341.  
  342. If you register this program, you can download the full documentation which 
  343. describes how to use the additional parameters (optionally you can figure out 
  344. *some* of them from looking at the demo programs <grin>).
  345.  
  346. The added functions include:
  347.  
  348. o  Window hiliting:  highlight all text in a window (leave color)
  349. o  Window fading:    opposite of above
  350. o  Window scrolling: up, down, left, right, any color
  351. o  Window coloring:  color windows but leave text intact--you can "hide" and
  352.                      "unhide" text this way if you're devious like me
  353. o  Window blanking:  any color
  354. o  Screen save/restore: up to two screens in memory, others can be read/written
  355.                          from/to disk files
  356. o  XOR bits:         XOR any bits for any window, which allows fading, 
  357.                      highlighting, blinking, color masking, etc.
  358. o  OR bits:          Same as XOR but sets bits on instead of reversing them
  359. o  Cursor on/off:    It was in there anyway, why not?
  360. o  Junk a window:    Just for me <grin>
  361. o  Dissolve text:    Also mostly for me, but it might be useable
  362. o  Zap text
  363. o  "Cloning"         "Clone" LITEBAR with a coupla screens and a menu built in!
  364. o  Banners
  365. o  Programmable "first option"
  366.  
  367. Anyway, I hope you enjoy the program; I worked hard on it.  If you have any
  368. suggestions for improvements, drop me a note or leave Email on Compuserve.
  369. Enjoy!
  370.  
  371. RRF
  372.  
  373. PS:
  374. ___
  375. My phone number is not included here because I'm tired of answering 
  376. support calls for non-registered users.  Even for registered users,
  377. $20 does *not* buy any support.  If you're reasonable, I will attempt to
  378. support the product (in this case *I* define reasonable <grin>).  This is 
  379. *not* a product for beginning computer users, gang.
  380.  
  381. ________________________________________________________________________________
  382.  
  383.  
  384. LITEBAR order form:
  385.  
  386. send to:
  387. R. Russell Freeland
  388. Synergy Corp.
  389. 1780 SW 43 Ave.
  390. Ft. Lauderdale, FL 33317
  391. Compuserve: 76146,371
  392.  
  393. Yes, I am impressed with the incredibly cheap and versatile LITEBAR 4.2
  394. so much that I want to register the product.  I enclose ($40) __________.
  395.  
  396. or:
  397.  
  398. Yes, I agree, LITEBAR only crashes and burns when you misplace a comma. I
  399. am so impressed with the honesty of your documentation that I want to register
  400. for the whole set of Synergy utilities.  I enclose ($75) ________________.
  401.  
  402. Check one (√):
  403.  
  404.  1) Just set me up on your BBS and give me the number.  I can download without
  405.      any help from the likes of you.  Leave me a message on Compuserve with
  406.      the password and BBS number.
  407.  
  408.  2) Set me up on your BBS. I don't like Compuserve or I use it too compulsively,
  409.      send me a postcard or something with my password and the BBS number.
  410.  
  411.  3) I could care less about your stupid BBS.  Just cash the check and buy some
  412.      groceries.
  413.  
  414.  4) I don't have a modem.  Send me the source code and expanded documentation
  415.      (for whatever I filled in above) on disk.  I include an extra $5 for this
  416.      service.  My machine uses (√):
  417.  
  418.         ___ 3.5 inch diskettes, 720K
  419.  
  420.         ___ 5.25 inch diskettes, 360K
  421.  
  422.         ___ 5.25 inch diskettes, 1.2M or 360K
  423.  
  424.         ___ Some other bizarre disk format that you're gonna have real trouble
  425.             duplicating.
  426.  
  427. (If you are one of those unfortunate souls without a modem to your name, please
  428. don't expect second-day air delivery.  Strange as it may seem, I do have to
  429. work for a living <yuk> and it'll take at least 2 weeks to get a disk out
  430. around here.)
  431.  
  432. Name:_______________________________________________________________________
  433.  
  434. Company:____________________________________________________________________
  435.  
  436. Street Address:_____________________________________________________________
  437.  
  438. City, State, Zip: __________________________________________________________
  439.  
  440. Compuserve number:____________________
  441.  
  442. Phone:__________________________________________________   Comments:____
  443.  
  444.